Copyright: Copyright 1995-1996, Catalyst Development Corp.


Contents
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench
 Introduction to Windows Sockets

 Programming with SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes


Section 0.0 - Installing SocketWrench
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Windows 3.1

 Windows 95

 Windows NT 3.51

 Introduction to Windows Sockets

 Programming with SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes


0.1 Windows 3.1
Installing SocketWrench on Windows 3.1

To install SocketWrench on Windows 3.1 or Windows for Workgroups 3.11, run the installation utility that is included with the package. If the package was downloaded from a bulletin board system, it will be necessary to extract the files from an archive. To install the software, select File|Run from the Program Manager menu. A dialog box will prompt you for the name of the program to execute. If you are installing from a diskette, enter a:\setup. Otherwise, specify the complete path where the setup utility is located.

When the installation begins, you will be prompted to enter the name of a directory where documents and sample programs can be installed. If the directory does not exist, you can choose to have the setup utility create it for you.

The SocketWrench control and help file will be copied to the \WINDOWS\SYSTEM directory along with the other Visual Basic controls. After all of the files have been installed, you will be prompted if you wish to create a program group for the help and documentation files.

It is required that you have a a Windows Sockets 1.1 compatible library installed on your system. For those systems running Windows for Workgroups, a free 32-bit stack can be downloaded from Microsoft's anonymous FTP server:

Hostname:	ftp.microsoft.com
Username:	anonymous
Password:	[your email address]
File:	/peropsys/windows/public/tcpip/wfwt32.exe
This self-extracting executable contains the drivers necessary to add the TCP/IP protocol to an existing network configuration.


0.2 Windows 95
Installing SocketWrench on Windows 95

To install SocketWrench on Windows 95, run the installation utility that is included with the package. If the package was downloaded from a bulletin board system, it will be necessary to extract the files from an archive. To install the software, click the Start button and then select Run. A dialog box will prompt you for the name of the program to execute. If you are installing from a diskette, enter a:\setup. Otherwise, specify the complete path where the setup utility is located.

When the installation begins, you will be prompted to enter the name of a directory where documents and sample programs can be installed. If the directory does not exist, you can choose to have the setup utility create it for you.

The SocketWrench control and help file will be copied to the \WINDOWS\SYSTEM directory along with the other Visual Basic controls. After all of the files have been installed, you will be prompted if you wish to create a program group for the help and documentation files.


0.3 Windows NT
Installing SocketWrench on Windows NT 3.51

To install SocketWrench on Windows NT 3.51, run the installation utility that is included with the package. If the package was downloaded from a bulletin board system, it will be necessary to extract the files from an archive. To install the software, select File|Run from the Program Manager menu. A dialog box will prompt you for the name of the program to execute. If you are installing from a diskette, enter a:\setup. Otherwise, specify the complete path where the setup utility is located.

When the installation begins, you will be prompted to enter the name of a directory where documents and sample programs can be installed. If the directory does not exist, you can choose to have the setup utility create it for you.

The SocketWrench control and help file will be copied to the \WINDOWS\SYSTEM directory along with the other Visual Basic controls. After all of the files have been installed, you will be prompted if you wish to create a program group for the help and documentation files.


Section 1.0 - Windows Sockets
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Introduction to Windows Sockets

 Introduction
 Transmission Control Protocol
 User Datagram Protocol
 Hostnames
 Service Ports
 Sockets
 The Client-Server Model
 Blocking vs. Non-blocking Sockets

 Programming with SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes


1.0 Introduction to Windows Sockets
Introduction to Windows Sockets

With the acceptance of TCP/IP as a standard platform-independent network protocol, and the explosive growth of the Internet, the Windows Sockets API (application programming interface) has emerged as the standard for network programming in the Windows environment. This document will introduce  the basic concepts behind Windows Sockets programming and get you started with your first application. If you’re already familiar with sockets programming, feel free to skip this section. It is assumed that the reader is familiar with Visual Basic and has installed the SocketTools or SocketWrench package.

The Windows Sockets specification was created by a group of companies, including Microsoft, in an effort to standardize the TCP/IP suite of protocols under Windows. Prior to Windows Sockets, each vendor developed their own proprietary libraries, and although they all had similar functionality, the differences were significant enough to cause problems for the software developers that used them. The biggest limitation was that, upon choosing to develop against a specific vendor’s library, the developer was "locked" into that particular implementation. A program written against one vendor’s product would not work with another’s. Windows Sockets was offered as a solution, leaving developers and their end-users free to choose any vendor’s implementation with the assurance that the product will continue to work.

There are two general approaches that you can take when creating a Visual Basic program that uses Windows Sockets: code directly against the API, or use a custom control (VBX or OCX) which provides an interface to the library by setting properties and responding to events. The first approach, while possible, is not recommended. The Windows Sockets API was designed for use by C programmers, and some of the functions are fairly unpleasant to use in the Visual Basic environment. You’ll end up writing a great deal of code geared towards working around the incompatibilities between the API and Visual Basic, rather than writing the code for your application.

A custom control provides a more "natural" programming interface, and allows you to avoid much of the error-prone drudgery commonly associated with sockets programming. By dropping the control on a form, setting some properties and responding to events, you can quickly and easily write an Internet-enabled application. And because of the nature of custom controls in general, the learning curve is low and experimentation is easy. SocketWrench provides a comprehensive interface to the Windows Sockets library and will be used to build a simple client-server application in the next section of this document. The SocketTools controls provide a higher level interface to many of the application protocols used over the Internet. Before we get started with the controls, however, we’ll cover the basic terminology and concepts behind sockets programming in general.


1.1 Transmission Control Protocol
Introduction to Windows Sockets

Transmission Control Protocol

When two computers wish to exchange information over a network, there are several components that must be in place before the data can actually be sent and received. Of course, the physical hardware must exist, which typically includes network interface cards (NICs) and wiring of some type to connect them. Beyond this physical connection, however, computers also need to use a protocol which defines the parameters of the communication between them. In short, a protocol defines the "rules of the road" that each computer must follow so that all of the systems in the network can exchange data. One of the most popular protocols in use today is TCP/IP, which stands for Transmission Control Protocol/Internet Protocol.

By convention, TCP/IP is used to refer to a suite of protocols, all based on the Internet Protocol (IP). Unlike a single local network, where every system is directly connected to each other, an internet is a collection of networks, combined into a single, virtual network. The Internet Protocol provides the means by which any system on any network can communicate with another as easily as if they were on the same physical network. Each system, commonly referred to as a host, is assigned a unique 32-bit number which can be used to identify it over the internetwork. Typically, this address is broken into four 8-bit numbers separated by periods. This is called dot-notation, and looks something like "192.43.19.64". Some parts of the address are used to identify the network that the system is connected to, and the remainder identifies the system itself. Without going into the minutia of the Internet addressing scheme, just be aware that there are three "classes" of addresses, referred to as "A", "B" and "C". he rule of thumb is that class "A" addresses are assigned to very large networks, class "B" addresses are assigned to medium sized networks, and class "C" addresses are assigned to smaller networks (networks with less than approximately 250 hosts).

When a system sends data over the network using the Internet Protocol, it is sent in discrete units called datagrams, also commonly referred to as packets. A datagram consists of a header followed by application-defined data. The header contains the addressing information which is used to deliver the datagram to it’s destination, much like an envelope is used to address and contain postal mail. And like postal mail, there is no guarantee that a datagram will actually arrive at it’s destination. In fact, datagrams may be lost, duplicated or delivered out of order during their travels over the network. Needless to say, this kind of unreliability can cause a lot of problems for software developers. What’s really needed is a reliable, straight-forward way to exchange data without having to worry about lost packets or jumbled data.

To fill this need, the Transmission Control Protocol (TCP) was developed. Built on top of IP, TCP offers a reliable, full-duplex byte stream which may be read and written to in a fashion similar to reading and writing a file. The advantages to this are obvious: the application programmer doesn’t need to write code to handle dropped or out-of-order datagrams, and instead can focus on the application itself. And because the data is presented as a stream of bytes, existing code can be easily adopted and modified to use TCP.

TCP is known as a connection-oriented protocol. In other words, before two programs can begin to exchange data they must establish a "connection" with each other. This is done with a three-way handshake in which both sides exchange packets and establish the initial packet sequence numbers (the sequence number is important because, as mentioned above, datagrams can arrive out of order; this number is used to ensure that data is received in the order that it was sent). When establishing a connection, one program must assume the role of the client, and the other the server. The client is responsible for initiating the connection, while the server’s responsibility is to wait, listen and respond to incoming connections. Once the connection has been established, both sides may send and receive data until the connection is closed.


1.2 User Datagram Protocol
Introduction to Windows Sockets

User Datagram Protocol

Unlike TCP, the User Datagram Protocol (UDP) does not present data as a stream of bytes, nor does it require that you establish a connection with another program in order to exchange information. Data is exchanged in discrete units called datagrams, which are similar to IP datagrams. In fact, the only features that UDP offers over raw IP datagrams are port numbers and an optional checksum.

UDP is sometimes referred to as an unreliable protocol because when a program sends a UDP datagram over the network, there is no way for it to know that it actually arrived at it’s destination. This means that the sender and receiver must typically implement their own application protocol on top of UDP. Much of the work that TCP does transparently (such as generating checksums, acknowledging the receipt of packets, retransmitting lost packets and so on) must be performed by the application itself.

With the limitations of UDP, you might wonder why it’s used at all. UDP has the advantage over TCP in two critical areas: speed and packet overhead. Because TCP is a reliable protocol, it goes through great lengths to insure that data arrives at it’s destination intact, and as a result it exchanges a fairly high number of packets over the network. UDP doesn’t have this overhead, and is considerably faster than TCP. In those situations where speed is paramount, or the number of packets sent over the network must be kept to a minimum, UDP is the solution.


1.3 Hostnames
Introduction to Windows Sockets

Hostnames

In order for an application to send and receive data with a remote process, it must have several pieces of information. The first is the IP address of the system that the remote program is running on. Although this address is internally represented by a 32-bit number, it is typically expressed in either dot-notation or by a logical name called a hostname. Like an address in dot-notation, hostnames are divided into several pieces separated by periods, called domains. Domains are hierarchical, with the top-level domains defining the type of organization that network belongs to, with sub-domains further identifying the specific network.

In this figure, the top-level domains are gov (government agencies), com (commercial organizations), edu  (educational institutions) and net (Internet service providers). The fully qualified domain name is the specified by naming the host and each parent sub-domain above it, separating them with periods. For example, the fully qualified domain name for the mars host would be mars.olympus.com. In other words, the system mars is part of the olympus domain (a company’s local network) which in turn is part of the com domain (a domain used by all commercial enterprises).

In order to use a hostname instead of a dot-address to identify a specific system or network, there must be some correlation between the two. This is accomplished by one of two means: a local host table or a name server. A host table is a text file that lists the IP address of a host, followed by the names that it’s known by. Typically this file is named hosts and is found in the same directory in which the TCP/IP software has been installed. A name server, on the other hand, is a system (actually, a program running on a system) which can be presented with a hostname and will return that host’s IP address. This approach is advantageous because the host information for the entire network is maintained in one centralized location, rather than being scattered about on every host on the network.


1.4 Service Ports
Introduction to Windows Sockets

Service Ports

In addition to the IP address of the remote system, an application also needs to know how to address the specific program that it wishes to communicate with. This is accomplished by specifying a service port, a 16-bit number that uniquely identifies an application running on the system. Instead of numbers, however, service names are usually used instead. Like hostnames, service names are usually matched to port numbers through a local file, commonly called services. This file lists the logical service name, followed by the port number and protocol used by the server.

 A number of standard service names are used by Internet-based applications and these are referred to as well-known services. Some common services are:

Service Name	Function
echo	Used to echo data back to the program that sent it. This is commonly used to test an application to make sure that a network connection can be established successfully.
ftp	Used to transfer files between computer systems using the File Transfer Protocol.
http	Used to retrieve documents and images from a World Wide Web server using the Hypertext Transfer Protocol.
pop3	Used to retrieve mail messages on a mail host using the Post Office Protocol.
smtp	Used to send electronic mail to a remote host using the Simple Mail Transfer Protocol.
telnet	Used to provide terminal emulation services for the remote host.
Remember that a service name or port number is a way to address an application running on a remote host. Because a particular service name is used, it doesn’t guarantee that the service is available, just as dialing a telephone number doesn’t guarantee that there is someone at home to answer the call.


1.5 Sockets
Introduction to Windows Sockets

Sockets

The previous sections described what information a program needs to communicate over a TCP/IP network. The next step is for the program to create what is called a socket, a communications end-point that can be likened to a telephone. However, creating a socket by itself doesn’t let you exchange information, just like having a telephone in your house doesn’t mean that you can talk to someone by simply taking it off the hook. You need to establish a connection with the other program, just as you need to dial a telephone number, and to do this you need the socket address of application that you want to connect to. This address consists of three key parts: the protocol family, Internet Protocol (IP) address and the service port number.

We’ve already talked about the IP address and service port, but what’s the protocol family? It’s a number which is used to logically designate the group that a given protocol belongs to. Since the socket interface is general enough to be used with several different protocols, the protocol family tells the underlying network software which protocol is being used by the socket. In our case, the Internet Protocol family will always be used when creating sockets. With the protocol family, IP address of the system and the service port number for the program that you want to exchange data with, you’re ready to establish a connection.


1.6 Client-Server Model
Introduction to Windows Sockets

The Client-Server Model

Programs written to use TCP are developed using the client-server model. As mentioned previously, when two programs wish to use TCP to exchange data, one of the programs must assume the role of the client, while the other must assume the role of the server. The client application initiates what is called an active open. It creates a socket and actively attempts to connect to a server program. On the other hand, the server application creates a socket and passively listens for incoming connections from clients, performing what is called a passive open. When the client initiates a connection, the server is notified that some process is attempting to connect with it. By accepting the connection, the server completes what is called a virtual circuit, a logical communications pathway between the two programs. It’s important to note that the act of accepting a connection creates a new socket; the original socket remains unchanged so that it can continue to be used to listen for additional connections. When he server no longer wishes to listen for connections, it closes the original passive socket.

To review, there are five significant steps that a program which uses TCP must take to establish and complete a connection.  The server side would follow these steps:

1. Create a socket.
2. Listen for incoming connections from clients.
3. Accept the client connection.
4. Send and receive information.
5. Close the socket when finished, terminating the conversation.

In the case of the client, these steps are followed:

1. Create a socket.
2. Specify the address and service port of the server program.
3. Establish the connection with the server.
4. Send and receive information.
5. Close the socket when finished, terminating the conversation.

Only steps two and three are different, depending on if it’s a client or server application.


1.7 Blocking vs. Non-Blocking Sockets
Introduction to Windows Sockets

Blocking vs. Non-Blocking Sockets

One of the first issues that you’ll encounter when developing your Windows Sockets applications is the difference between blocking and non-blocking sockets. Whenever you perform some operation on a socket, it may not be able to complete immediately and return control back to your program. For example, a read on a socket cannot complete until some data has been sent by the remote host. If there is no data waiting to be read, one of two things can happen: the function can wait until some data has been written on the socket, or it can return immediately with an error that indicates that there is no data to be read.

The first case is called a blocking socket. In other words, the program is "blocked" until the request for data has been satisfied. When the remote system does write some data on the socket, the read operation will complete and execution of the program will resume. The second case is called a non-blocking socket, and requires that the application handle the situation appropriately. Programs that use non-blocking sockets typically use one of two methods when sending and receiving data. The first method, called polling, is when the program periodically attempts to read or write data from the socket using a timer. The second, and preferred method, is to use what is called asynchronous notification. This means that the program is notified whenever a socket event takes place, and in turn can respond to that event. For example, if the remote program writes some data to the socket, a "read event" is generated so that program knows it can read the data from the socket at that point.

For historical reasons, the default behavior is for socket functions to "block" and not return until the operation has completed. Under Windows this can introduce some special problems because when the program blocks, it enters what is called a "message loop", where it continues to process messages sent to it by Windows and other applications. Since messages are being processed, this means that the program can be re-entered at a different point, with the blocked operation "parked" on the program’s stack. For example, consider a program that attempts to read some data from the socket when a button is pressed. Because no data has been written yet, it blocks and the program goes into a message loop. The user then presses a different button, which causes code to be executed, which in turn attempts to read data from the socket, and so on. Obviously, this can pose a big problem. To resolve it, the Windows Sockets standard states that there may only be one outstanding blocked call per thread of execution. This eans that, in the example given above, the second read would fail with an error indicating that a blocking operation is already in progress. While blocking sockets may be convenient in some situations, their use is generally discouraged because of the complications that they can introduce into the program.

The SocketTools controls facilitate the use of non-blocking sockets by firing events when appropriate. For example, a Read event is generated whenever the remote host writes on the socket, which tells your application that there is data waiting to be read. The use of non-blocking sockets will be demonstrated in the next section, and is one of the key areas in which a control has a distinct advantage over coding directly against the Windows Sockets API.


Section 2.0 - SocketWrench
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Introduction to Windows Sockets

 Programming with SocketWrench

 Introduction
 System Requirements
 A Sample Client Program
 Building An Echo Server
 Putting It All Together

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes


2.0 Programming with SocketWrench
Programming With SocketWrench

Because SocketWrench has a large number of properties, you might feel overwhelmed when you start reading through the technical reference material. Don’t worry -- you only need to understand how to use a handful of properties and events to get started. Once you’ve become more comfortable and knowledgeable about sockets programming, you’ll appreciate the power and flexibility that SocketWrench gives you.

Each control that you use corresponds to one socket, which may or may not be connected to a remote host. If you need access to multiple sockets, you must use multiple controls, typically as a control array. This is most commonly needed when your application acts a server and must be able to handle several connections at one time.


2.1 System Requirements
Programming With SocketWrench

System Requirements

The SocketWrench control requires Microsoft Windows 3.1 or later, Visual Basic 3.0 or later and a TCP/IP protocol stack with a Windows Sockets 1.1 compliant library. Microsoft has a free TCP/IP implementation for Windows for Workgroups 3.11 and Windows 95 includes TCP/IP as part of the base operating system.

For those systems that do not have a network connection, Catalyst includes a "loopback" library that supports the complete Windows Sockets API. It can be used to simulate a network connection so that applications using SocketWrench can function. Refer to the release notes for further information on installing and configuring the loopback library.


2.2 A Sample Client Program
Programming With SocketWrench

A Sample Client Program

The sample program that will be used throughout this document is a simple tool that can be used to connect with an echo server, a program which echoes back any data that’s sent to it. Later on, we’ll also cover how to implement your own echo server.

The first step, after starting Visual Basic, is to include the SocketWrench control in your new project. In Visual Basic 3.0, select the File|Add File option from the menu and a file selection dialog will be displayed. Enter the complete pathname of the control, such as c:\windows\system\cswskctl.vbx.

 In Visual Basic 4.0, select Tools|Custom Controls. If you are using the OCX, simply check the SocketWrench control in the list of available controls. If you are adding a VBX to the 16-bit version of VB4, click on the Browse button and enter the full pathname of the control in the file selection dialog.

After the control has been added to the tool palette, you will also need to include the CSTOOLS.BAS file that was copied to the directory that you specified during installation. Select the File|Add File menu option and enter the full pathname of the file (this procedure is the same for both versions 3.0 and 4.0 of Visual Basic).

To begin, you’ll need to create a form that has three labels, three text controls, a button and the SocketWrench control. The form might look something like this:

When executed, the user will enter the name or IP address of the system in the Text1 control, the text that is to be echoed in the Text2 control, and the server’s reply will be displayed in the Text3 control. The Command1 button will be used to establish a connection with the remote server. The Text2 and Text3 controls should be created with their Enabled properties initially set to False.

Some essential properties of the SocketWrench control, called Socket1, needs to be initialized.. The best place to do this is in the form’s Load subroutine. The code should look like this:

Sub Form_Load ()
    Socket1.AddressFamily = AF_INET
    Socket1.Protocol = IPPROTO_IP
    Socket1.SocketType = SOCK_STREAM
    Socket1.Binary = False
    Socket1.BufferSize = 1024
    Socket1.Blocking = False
End Sub

These six properties should be set for every instance of the SocketWrench control:

AddressFamily	This property is part of the socket address, and should always be set to a value of AF_INET, which is global constant with the integer value of 2. At this time, the Windows Sockets interface only supports the IP address family.
Protocol	This property determines which protocol is going to be used to communicate with the remote application. Most commonly, the value IPPROTO_IP is used, which means that the protocol appropriate for the socket type will be used.
SocketType	This property specifies the type of socket that is to be created. It may be either of type SOCK_STREAM or SOCK_DGRAM. The stream-based socket uses the TCP protocol, and data is read and written on the socket as a stream of bytes, similar to how data in a file is accessed. The datagram-based socket uses the UDP protocol, and data is read and written in discrete units called datagrams. Most sockets that you will create will be of the stream variety.
Binary	This property determines how data should be read from the socket. If set to a value of True, then the data is received unmodified. If set to False, the data is interpreted as text, with the carriage return and linefeed characters stripped from the data stream. Each receive returns exactly one line of text.
BufferSize	This property is used only for stream-based (TCP) sockets. It specifies the amount of memory, in bytes, that should be allocated for the socket’s send and receive buffers.
Blocking	This property specifies if the application should wait for a socket operation to complete before continuing. By setting this property to False, that indicates that the application will not wait for the operation to complete, and instead will respond to events generated by the control. This is the recommended approach to take when designing your application.
The next step is to establish a connection with the echo server. This is done by including code in the Command1 button’s Click event. The code should look like this:

Sub Command1_Click ()
    Socket1.HostName = Trim$(Text1.Text)
    Socket1.RemotePort = IPPORT_ECHO
    Socket1.Action = SOCKET_CONNECT
End Sub

The Text1 edit control should contain the name or IP address of a system that has an echo server running (most UNIX and Windows NT based systems do have such a server). The properties which have been used to establish the connection are:

HostName	This property should be set to either the host name of the system that you want to connect to, or it’s IP address in dot-notation.
RemotePort	This property should be set to the number of the port which the remote application is listening on. Port numbers below 1024 are considered reserved by the system. In this example, the echo server port number is 7, which is specified by using the global constant IPPORT_ECHO.
Action	This property initiates some action on the socket. The SOCKET_CONNECT action tells the control to establish a connection using the appropriate properties that have been set. A related action, SOCKET_CLOSE, instructs the control to close the connection, terminating the conversation with the remote server.
Both HostName and RemotePort are known as reciprocal properties. This means that by changing the property, the another related property will also change to match it. For example, when you assign a value to the HostName property, the control will determine it’s IP address and automatically set the HostAddress property to the correct value. The reciprocal property for RemotePort is the RemoteService property. For more information about these properties, refer to the SocketTools Technical Reference.

Because the socket is non-blocking (i.e.: the Blocking property has been set to a value of False), the program will not wait for the connection to be established. Instead, it will return immediately and respond to the Connect event in the SocketWrench control. The code for that event should look like this:

Sub Socket1_Connect ()
    Text2.Enabled = True
    Text3.Enabled = True
End Sub

This tells the application that when a connection has been established, enable the edit controls so that the user can send and receive information from the server.

Now that the code to establish the connection has been included, the next step is to actually send and receive data to and from the server. To do this, the Text2 control should have the following code added to it’s KeyPress event:

Sub Text2_KeyPress (KeyAscii As Integer)
    If KeyAscii = 13 Then
        Socket1.SendLen = Len(Text2.Text)
        Socket1.SendData = Text2.Text
        KeyAscii = 0: Text2.Text = ""
    End If
End Sub

If the user presses the Enter key in the Text2 control, then that text is sent down to the echo server. The properties used to send data are as follows:

SendLen	This property specifies the length of the data being sent to the server. It should always be set before the data is written to the socket. After the data has been sent, the value of the property is adjusted to indicate the actual number of bytes that have been written.
SendData	Setting this property causes the data assigned to it to be written to the socket. The number of bytes actually written may be less than the amount specified in the SendLen property if the socket buffers become full.
Once the data has been sent to the server, it immediately sends the data back to the client. This generates a Read event in SocketWrench, which should have the following code:

Sub Socket1_Read (DataLength As Integer, IsUrgent As Integer)
    Socket1.RecvLen = DataLength
    Text3.Text = Socket1.RecvData
End Sub

The properties used to receive the data are as follows:

RecvLen	This property specifies the maximum number of bytes that should be read from the socket. After the data has been received, the value is changed to reflect the number of bytes actually read.
RecvData	Reading this property causes data to be read from the socket, up to the maximum number of bytes specified by the RecvLen property. If the socket is non-blocking and there is no data to be read, an error is generated.
The Read event is passed two parameters, the number of bytes that are available to be read, and a flag that specifies if the data is urgent (also known as "out-of-band" data, the use of urgent data is an advanced topic outside of the scope of this document).

The last piece of code to add to the sample is to handle closing the socket when the program is terminated by selecting Close on the system menu. The best place to put socket cleanup code in the form’s Unload event, such as:

Sub Form_Unload (Cancel As Integer)
    If Socket1.Connected Then Socket1.Action = SOCKET_CLOSE
    End
End Sub

This should be rather self-explanatory. The only new property that has been introduced is the Connected property, which is a Boolean flag. If it is True, then a connection has been established. With all of the properties and event code needed for the sample client application completed, all that’s left to do is run the program!

The first thing that you’ll probably notice is that if you specify an incorrect host name or address, an error will be generated and the program will stop. Of course, in a real application you’d need to provide extensive error checking. SocketWrench errors start at 24,000 and correspond to the error codes used by the Windows Sockets library. Most errors will occur when setting the host name, address, service port or Action property.


2.3 Building An Echo Server
Programming With SocketWrench

Building An Echo Server

The next step is to implement your own echo server. To accomplish this, we’ll modify the client application to function as a server as well. The side benefit is that this will allow you to test both the client and server application on your local system.

Remember that the first thing that a server application must do is listen on a local port for incoming connections. You know that an application is attempting to connect with you when the Accept event is generated for the SocketWrench control. There are two methods which you can use to accept an incoming connection: set the Action property to the value SOCKET_ACCEPT, or set the Accept property.

Setting the Action property is the simplest of the two methods. As you’ll recall, the act of accepting a connection causes a second socket to be created. The original listening socket continues to listen for more connections, while the second socket can be used to communicate with the client that connected to you. When you set the Action property to SOCKET_ACCEPT, what you’re telling the control to do is to close the original listening socket, and from that point on, the control can be used to communicate with the client. While this is convenient, it is also limiting -- since the listening socket has been closed, no more clients can connect with your program, effectively limiting it to a single client connection.

The more flexible approach is to set the Accept property to the value passed as an argument to the Accept event. However, this cannot be done by the control that is listening for connections because it is in use. You have to use another, unused control to accept the connection. The problem is, how many clients are going to attempt to connect to you? Of course, you could drop a fixed number of SocketWrench controls on your form, thereby limiting the number of connections, but that’s not a very good design. The better approach is to create a control array which can be dynamically loaded when a connection is attempted by a client, and unloaded when the connection is closed. This is the approach that we’ll take in our server code sample.

The first thing to do is to add a second SocketWrench control to your form, and make it a control array. Initially there will only be one control in the array, identified as Socket2(0). This control will be responsible for listening for client connections. Just as with the client socket control, several of the control’s properties should be initialized in the form’s Load subroutine. The new subroutine should look like this:

 Sub Form_Load ()
    Socket1.AddressFamily = AF_INET
    Socket1.Protocol = IPPROTO_IP
    Socket1.SocketType = SOCK_STREAM
    Socket1.Binary = False
    Socket1.BufferSize = 1024
    Socket1.Blocking = False

    Socket2(0).AddressFamily = AF_INET
    Socket2(0).Protocol = IPPROTO_IP
    Socket2(0).SocketType = SOCK_STREAM
    Socket2(0).Blocking = False
    Socket2(0).LocalPort = IPPORT_ECHO
    Socket2(0).Action = SOCKET_LISTEN
    LastSocket = 0
End Sub

The only thing that is new here is the LocalPort property and the LastSocket variable. The LocalPort property is used by server applications to specify the local port that it’s listening on for connections. By specifying the standard port used by echo servers, any other system can connect to yours and expect the program to echo back whatever is sent to it.

The LastSocket variable is defined in the "general" section of the Visual Basic application as an integer. It is used to keep track of the next index value that can be used in the control array.

By setting the Action property to SOCKET_LISTEN in the form’s Load event, the program will start listening for connections as soon as the program starts executing. When a client tries to connect with your server, Socket2’s Accept event will fire. The code for this event should look like this:

Sub Socket2_Accept (Index As Integer, SocketId As Integer)
    Dim I As Integer
    For I = 1 To LastSocket
        If Not Socket2(I).Connected Then Exit For
    Next I
    If I > LastSocket Then
        LastSocket = LastSocket + 1: I = LastSocket
        Load Socket2(I)
    End If
    Socket2(I).AddressFamily = AF_INET
    Socket2(I).Protocol = IPPROTO_IP
    Socket2(I).SocketType = SOCK_STREAM
    Socket2(I).Binary = True
    Socket2(I).BufferSize = 1024
    Socket2(I).Blocking = False
    Socket2(I).Accept = SocketId
End Sub

The first statement loads a new instance of the SocketWrench control as part of the Socket2 control array. The next six lines initialize the control’s properties, and then the Accept property is set to the value of the SocketId parameter that is passed to the control. After executing this statement, the control is now ready to start communicating with the client program.

Since it’s the job of an echo server to echo back whatever is sent to it, we have to add code to the control’s Read event, which tells it that the client has sent some data to us. It looks like this:

Sub Socket2_Read (Index As Integer, DataLength As Integer,
                  IsUrgent As Integer)
    Socket2(Index).RecvLen = DataLength
    Socket2(Index).SendLen = DataLength
    Socket2(Index).SendData = Socket2(Index).RecvData
End Sub

Finally, when the client closes the connection, the socket control must also close it’s end of the connection. This is accomplished by adding a line of code in the socket’s Disconnect event:

Sub Socket2_Disconnect (Index As Integer)
    Socket2(Index).Action = SOCKET_CLOSE
End Sub

To make sure that all of the socket connections are closed when the application is terminated, the following code should be included in the form’s Unload event:

Sub Form_Unload (Cancel As Integer)
    Dim I As Integer
    If Socket1.Connected Then Socket1.Action = SOCKET_CLOSE
    If Socket2(0).Listening Then Socket2(0).Action = SOCKET_CLOSE
    For I = 1 To LastSocket
        If Socket2(I).Connected Then Socket2(I).Action = SOCKET_CLOSE
    Next I
    End
End Sub

The only new property shown here is the Listening property, which like the Connected property, is a Boolean flag. If the control is listening for incoming connections, this property will return True, otherwise it returns False. This is added only as an extra "sanity check", and the property should always return True for this instance of the control.


2.4 Putting It All Together
Programming With SocketWrench

Putting It All Together

This document has introduced you to the basic concepts behind socket programming, and how to use SocketWrench to get started developing your own TCP/IP applications. Although the echo client and server sample program is fairly basic, it does illustrate many of the key issues that you’ll encounter when developing your own software.

Now is a good time to review the SocketTools Technical Reference and the other sample programs included with the SocketTools distribution. Also, the help file included with SocketTools includes all of the information in the Technical Reference at your fingertips.


Section 3.0 - General Information
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Introduction to Windows Sockets

 Programming with SocketWrench

 SocketWrench General Information

 Catalyst SocketWrench

  Catalyst SocketTools

  Current Version of SocketWrench

  Supported Platforms

  Commercial Use

  Copyright

  License Agreement

  Technical support for SocketWrench

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes


3.1 Catalyst SocketWrench
SocketWrench General Information

Catalyst SocketWrench

SocketWrench/VB is a custom control which uses the Windows Sockets API to provide basic TCP/IP networking functionality to your application. Both client and server capability is provided through the control, as well as support for both TCP and UDP protocols. Virtually any type of application which needs to communicate with another, either on a local network or over the Internet, can be written using SocketWrench/VB.

Unlike many other controls that break functionality into several components (such as one control for TCP, another for UDP and yet another for server functionality) SocketWrench/VB provides everything that you need in one control.


3.2 Catalyst SocketTools
SocketWrench General Information

Catalyst SocketTools

Catalyst SocketTools is collection of custom controls designed to allow you, the developer, to quickly and easily build network-aware applications using the standard Windows Sockets interface and TCP/IP vendor stack of your choice. The controls provide client interfaces for the major application protocols, and by simply selecting the control into your application and setting a few properties, you're on your way to an Internet-aware application. Included in the package are the following controls:

	Domain Name Service		Remote Command Execution
	File Transfer Protocol		Simple Mail Transfer Protocol
	Image Viewer		Telnet Network Terminal
	Internet Control Message Protocol		Terminal Emulator
	Network News Protocol		Windows Sockets
	Post Office Protocol		World Wide Web Browser
	Remote Access Service
Both 16-bit VBX and 16/32-bit OCX controls are included in the same package, along with comprehensive samples and both printed and on-line documentation. To make your (and our) life simpler, there aren't multiple package sets to pick from and there are never any royalty or runtime licensing fees for any of our controls. You get everything that's available for one reasonable price, without the hassles. For further information about SocketTools, you can visit us at our World Wide Web site at:

http://www.catalyst.com/

To correspond with us by postal mail, you can contact us at:

Catalyst Development Corporation
56925 Yucca Trail, Suite 254
Yucca Valley, California 92284

Phone:	(800) 776-3818 (619) 228-9653
Fax:	(619) 369-1185
Email:	sales@catalyst.com


3.3 Current Version
SocketWrench General Information

Current Version

The current version of the control is 2.0a, and is available at a number of sites. On CompuServe it is available in the MSBASIC forum as cswsk20a.zip. On the Internet, it is available on your local SimTel mirror site in the /win3/visbasic directory as cswsk20a.zip. You can always find the latest copy of the package on the Catalyst Software Web site at http://www.catalyst.com/


3.4 Supported Platforms
SocketWrench General Information

Supported Platforms

SocketWrench/VB will work with any TCP/IP stack that provides a Windows Sockets 1.1 compliant library. This includes the TCP/IP stacks that are part of the base operating system for Windows 95 and Windows NT. A free 32-bit TCP/IP stack can be obtained from Microsoft for Windows for Workgroups 3.11.

SocketWrench/VB can be used with Visual Basic 2.0 or later, including the 16-bit version of Visual Basic 4.0. Since VBXs are 16-bit controls, it cannot be used with the 32-bit version of VB 4.0.


3.5 Commercial Use
SocketWrench General Information

Commercial Use

SocketWrench/VB is freely re-distributable software. You may use the control in your own applications and redistribute the package as needed. However, SocketWrench/VB has not been placed in the public domain. Catalyst Development Corp. retains the copyright and may, without prior notice, release subsequent versions of SocketWrench/VB that are not freely re-distributable. As a developer, you may include the control in your applications as per the license agreement included with this software distribution.

We decided to make SocketWrench/VB freely available to developers in order to introduce them to our company and contribute something to the community that we will ultimately be marketing to. It also provided us with critical feedback on the features and functionality of the control. This is important because our commercial product, Catalyst SocketTools, shares many of the features found in SocketWrench/VB.

Catalyst is committed to providing the tools and component software that help developers meet the increasingly complex needs of their customers. However, please keep in mind that support for our commercial products will take priority over support for the free stand-alone SocketWrench package. If you are developing a commercial application, we recommend that you purchase the complete SocketTools package.


3.6 Copyright
Copyright © 1995-1996 Catalyst Development Corporation. All rights reserved.

SocketWrench and SocketTools are trademarks of Catalyst Development Corporation. Microsoft, Windows, Windows NT and Visual Basic are trademarks or registered trademarks of Microsoft Corporation.

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Catalyst Development Corporation.

The software described in this document is furnished under a license agreement. The software may be used only in accordance with the terms of the agreement. It is against the law to copy the software except as specifically allowed in the license agreement. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the purchaser's personal use, without the express written permission of Catalyst Development Corporation.


3.7 License Agreement
SocketWrench License Agreement

GRANT OF LICENSE.  CATALYST (Catalyst Development Corporation) grants to you, the end user, the right to use the Catalyst SocketWrench developers toolkit. (Known as the "SOFTWARE".) The SOFTWARE may be distributed to others, provided that the SOFTWARE is redistributed in it's original unmodified form, complete with all files, and no fee is charged for such distribution except for reasonable media and shipping charges..

DISTRIBUTION.  The user has a royalty-free right to reproduce and distribute executable files that incorporate the SOFTWARE. This right includes the distribution of the runtime module of the SOFTWARE, provided that the user: (a) distributes the runtime module only in conjunction with and as part of a software product; (b) includes a valid copyright notice on the software product; and (c) agrees to indemnify, hold harmless and defend the copyright holder against any claims or lawsuits, including attorney's fees, that arise from the use or distribution of your software product. The "runtime module" refers to the custom control library required during execution of your software product.

COPYRIGHT.  The SOFTWARE is owned by CATALYST and is protected by copyright laws and international treaty provisions. Therefore you must treat the SOFTWARE like any other copyrighted material (e.g. a book or musical recording), except that you may copy and redistribute the SOFTWARE in accordance with this license.

OTHER RESTRICTIONS.  You may not RENT or LEASE the SOFTWARE. You may not reverse engineer, decompile or disassemble the SOFTWARE, except to the extent such restriction is expressly prohibited by law. Except as described above, you may not legally copy or distribute the SOFTWARE (which includes the documentation, object code and supporting programs), in whole or in part. All rights not specifically granted are reserved by the copyright holder.

NO WARRANTY. The SOFTWARE is provided "AS-IS", without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the performance of the programs is with the user. CATALYST does not warrant that the operation of the programs will be uninterrupted or error-free. CATALYST assumes no responsibility or liability of any kind for errors in the programs or documentation, or for the consequences of any such errors. Should the the SOFTWARE prove defective, you assume the cost of all necessary servicing, repair or correction. Some states do not allow limitations on implied warranties, so the above limitations may not apply to you.

NO LIABILITY FOR CONSEQUENTIAL DAMAGES.  In no event shall CATALYST or its suppliers be liable for any damages whatsoever (including, with limitation, damages for loss of business profits, business interruption, or other pecuniary loss) arising out of the use or inability of this CATALYST product, even if CATALYST has been advised of such damages. This agreement is governed by the laws of the state of California.


3.8 Technical Support
SocketWrench General Information

Technical Support

The best way to contact us is via e-mail. If you have a product-related question, send it to info@catalyst.com. If you have a technical support question or problem, you can address it to support@catalyst.com.

If you have a technical support problem, please remember to include information about what TCP/IP stack you're using along with a detailed description of the problem. If possible, a sample project that reproduces the problem would be very helpful.

Please note that technical support for our commercial products will necessarily take first priority. If you are using SocketWrench for a commercial project, we encourage you to purchase a license for SocketTools. We are committed to providing the best possible support for all of our tools, but ask that developers using the free control request support through e-mail only.


Section 4.0 - Technical Information
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Introduction to Windows Sockets

 Programming with SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 Upgrading From Version 1.1

 New Control Properties

 Application Protocols

 Unable To Load Control

 General Protection Faults

 Dialup Internet Connections

 Windows 95 Dialer

 Remote Access Services

 Development Environments

 Local System Name

 Address Already In Use

 User Datagram Protocol

 SocketWrench Samples

 Compatibility Notes


4.1 Upgrading From Version 1.1
SocketWrench Technical Information

Upgrading From Version 1.1

The current version of SocketWrench is 2.0a. If you have developed applications using the SocketWrench/VB 1.x control, there are a number of significant changes that have been made with this release. A number of these changes were made to make SocketWrench easier to use and compatible with the other controls in the SocketTools toolkit.

The SocketWrench control file name has changed

The previous versions of the SocketWrench control were named CSWSOCK.VBX. The SocketWrench 2.0 control name has changed to to the following:

File Name	Description
CSWSKCTL.VBX	16-bit VBX for Visual Basic 3.0
CSWSK16.OCX	16-bit OCX for Visual Basic 4.0
CSWSK32.OCX	32-bit OCX for Visual Basic 4.0, Delphi 2.0 and Visual C++ 4.0

The CSWSOCK.BAS module was replaced with CSTOOLS.BAS

Previous versions of SocketWrench included a module named CSWSOCK.BAS which defined various constants that could be used with the control. These constants are included in the CSTOOLS.BAS module distributed with SocketTools.

The Windows Sockets library is dynamically loaded

Previous version of SocketWrench would automatically load the Windows Sockets library (WINSOCK.DLL) as soon as the control was placed on a form. If the library was missing or required a dial-up network connection, there application would terminate or generate unexpected errors.

All of the controls in the toolkit dynamically load the Windows Sockets library, and only when the control requires the library to be loaded. The following conditions cause the control to attempt to load the library:

• A host name or address is specified
• A local or remote port number or service name is specified
• A connection is attempted with a remote host

In addition, the SocketWrench control includes two new actions that allow you to explicitly load and unload the library on demand.

The Type property has been changed to SocketType

Earlier version of SocketWrench used a property named Type to specify the type of socket to be created. Since this is a reserved word in some environments, this property has been renamed to SocketType. You should replace all instances with the new property name in your application.

The Error event has been renamed to LastError

OLE controls have a standard error event which conflicted with the event used by the previous versions of the control. It has been renamed to LastError, and accepts the same parameters. You should replace all instances with the new event name in your application.

Text mode does not strip carriage returns or linefeeds

In previous versions of the control, setting the Binary property to False caused carriage returns and linefeeds to be stripped from the data being returned by a remote host. This made it difficult to determine the end-of-line on a partial read. The control now preserves these characters.

The LastError property returns Visual Basic error values

The LastError property would return a Windows Sockets error code, which did not match the errors returned by Visual Basic or those included in the CSWSOCK.BAS module. This has been changed so that LastError property returns the same error values generated by the control.


4.2 New Control Properties
SocketWrench Technical Information

New Control Properties

There are a number of new properties available in the SocketWrench 2.0 control. Please review these properties and consult the SocketWrench Technical Reference for additional information about how they can be used in your applications.

AutoResolve Property

By default, setting the HostName property causes the HostAddress property to automatically be updated with the IP address associated with that host. Likewise, setting the HostAddress property would cause the HostName property to be updated with the name of the host that was assigned the given address.

While convenient, this behavior could cause problems for those systems that were using DNS, especially over a dial-up Internet connection. Because setting the HostName or HostAddress property would result in a DNS query, it could cause the application to block, possibly for several seconds.

The AutoResolve property determines if host names and addresses are automatically resolved by the control. By default, this property is True, making the behavior compatible with previous versions of the controls. Setting this property False instructs the control to not attempt to resolve the host name or address until a connection is actually attempted.

Library Property

All of the SocketTools controls dynamically load the Windows Sockets library on demand. However, the controls would load the WINSOCK.DLL or WSOCK32.DLL using the standard method for loading libraries. Namely, it would:

Search the current working directory
Search the \WINDOWS directory
Search the \WINDOWS\SYSTEM or SYSTEM32 directory
Search each directory in the PATH environment variable

The application had no explicit control over which library would be loaded, except by changing it's current working directory or requiring that the user maintain the PATH environment variable.

The Library property, available in all of the networking related controls, allows the application to explicitly specify the full pathname of a Windows Sockets library that is to be loaded. It is not required that the module be named WINSOCK.DLL or WSOCK32.DLL, only that it export all of the functions required to comply with the Windows Sockets 1.1 specification.

By default, this property has no value, which causes the control to behave in the same way as previous versions. Once a Windows Sockets library is loaded, it becomes a read-only property, returning the full pathname of the module. Attempting to set the property after a library is loaded will result in a runtime error.

If you wish to explicitly specify a Windows Sockets library, it is recommended that you set the Library property in the Load event for the form on which the control has been placed.

If the control is unable to load the specified library, either because the file does not exist or because it was not a Windows Sockets 1.1 compatible library, a "Device unavailable" error will be generated. This error may also be generated if the control was unable to initialize the library due to an internal problem with the TCP/IP stack.

MaxDatagram Property

The MaxDatagram property returns the maximum number of bytes that may be transmitted in a single write operation on a SOCK_DGRAM type socket. Attempting to send more than this number of bytes will result in an error, with no data being written.

MaxSockets Property

The MaxSockets property returns the maximum number of sockets that may be created, system wide. This value is determined by the underlying TCP/IP stack.


4.3 Application Protocols
SocketWrench Technical Information

Application Protocols

The best resource for learning about the common application protocols are RFC's. These Request For Comment documents form the foundation of the application protocols used over the Internet. There are a great number of them, but some of the more common ones are:

RFC 821	Simple Mail Transfer Protocol (SMTP)
RFC 959	File Transfer Protocol (FTP)
RFC 977	Network News Transfer Protocol (NNTP)
RFC 1341	Multipurpose Internet Mail Extensions (MIME)
RFC 1436	Internet Gopher Protocol
RFC 1459	Internet Relay Chat Protocol (IRC)
RFC 1725	Post Office Protocol Version 3 (POP3)


4.4 Unable To Load Control
SocketWrench Technical Information

Unable To Load Control

Check to make sure that a Windows Sockets library is installed on the system, and that it's either in the \WINDOWS directory, or a directory that's specified in the PATH environment variable. The control may fail to load if this library, WINSOCK.DLL, cannot be loaded. Also check to make sure that there is enough free memory available to load both the control and the Windows Sockets library.


4.5 General Protection Faults
SocketWrench Technical Information

General Protection Faults

A general protection fault (GPF) typically occurs when an incorrect Windows Sockets library is being loaded by the control. Check to make sure that there is only one copy of a Windows Sockets library installed on your system, and that the correct library is being loaded. You can use the WPS utility (included with the Visual Basic 3.0 Professional edition or downloadable from Microsoft) to determine where the WINSOCK.DLL is being loaded from.


4.6 Dialup Internet Connections
SocketWrench Technical Information

Dialup Network Connections

SocketWrench can be used to build applications that work over dialup Internet connections, as well as with local and wide-area networks. However, SocketWrench does not have any direct control over a specific TCP/IP dialer application. To cause the control to automatically establish a connection with an Internet service provider (ISP), you must configure the TCP/IP stack appropriately.

It is not required that you have an active connection to your ISP when building your application using SocketWrench. The Windows Sockets library is only loaded by the control when the program is being executed and requires it's services.


4.7 Windows 95 Dialer
SocketWrench Technical Information

Windows 95 Dialer

Under Windows 95, the dialup networking services can be configured to automatically start the dialer when a network connection is attempted. However, this feature is only available to 32-bit applications. For those programs which need to automatically start the dialer, the RAS control should be used.


4.8 Remote Access Services
SocketWrench Technical Information

Remote Access Services

Microsoft's remote access services (RAS) is a collection of software that enables a client machine to connect to, and establish a network connection with, a remote server. These services may be used to establish a connection with an Internet service provider (ISP), providing a direct connection to the Internet.

The RAS control that is included with this package may be used to establish, monitor and terminate connections with a remote server. It can be used with the following platforms:

• Windows for Workgroups 3.11

• Windows 95

• Windows NT 3.51 or 4.0

It is required that the RAS services be installed and configured on the client system, with phonebook entries created for the specific Internet service providers.


4.9 Development Environments
SocketWrench Technical Information

Development Environments

The only development environment supported for the 16-bit Visual Basic controls (VBXs) is Visual Basic 2.0 or later. Specifically, the VBXs cannot be used in Visual C++ 1.5 or Delphi 1.0. This is because both Visual C++ and Delphi 1.0 only support controls written to the Visual Basic 1.0 specification. Because the SocketWrench VBX (and all of the other SocketTools VBXs) are built using the 2.0 specification, they are not compatible with those development environments.

The OLE controls (OCXs) may be used with any OLE control compatible container, such as Visual Basic 4.0, Visual C++ 4.0, Delphi 2.0 and others.


4.10 Local System Name
SocketWrench Technical Information

Local System Name

SocketWrench/VB attempts to determine your local host name and address by first calling a function to determine your local name(through a call to the gethostname() function, and then using that name, your IP address through a call to the gethostbyname() function. According to the Windows Sockets 1.1 specification, these functions should never fail when used in this manner.

However, some Windows Sockets libraries, notably the one included in Novell's Lan Workplace product, will not return the required information unless the system has an entry for itself in the local hosts file. This problem may also occur if you have a dialup network connection, using DNS for name resolution, and your host does not have a reverse (PTR) entry in the DNS database.


4.11 Address Already In Use
SocketWrench Technical Information

Address Already In Use

When an application closes a connection and attempts to establish another one, the error WSAEADDRINUSE may be generated. This occurs when the LocalPort property is not being reset before you establish the second connection.

By default, the LocalPort property has a value of zero (which is the same as IPPORT_ANY). What this tells the socket library is that you don't care what your local port number is, and for the library to assign you an unused port number greater than 1024.

After you connect to the server, the LocalPort property is modified to reflect the actual port number that was assigned to your socket. If, the next time you attempt to connect using that socket, the LocalPort property does not have a value of zero, it will attempt to use that specific port number, which may result in the error being generated. To correct the problem, simply insure that the LocalPort property has a value of zero before you attempt the connection


4.12 User Datagram Protocol
SocketWrench Technical Information

User Datagram Protocol

In addition to creating applications which use the Transmission Control Protocol (TCP), SocketWrench can also send and receive datagrams using the User Datagram Protocol (UDP). Refer to the SWUDP sample program for a generic example of using UDP with SocketWrench/VB.

In order to broadcast datagrams (that is, each machine on the local network will receive the datagram sent from your local host), you need to set the Broadcast property to True, and set the HostAddress property to the broadcast IP address for your network.


Section 5.0 - SocketWrench Samples
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench
 Introduction to Windows Sockets

 Programming With SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Visual Basic Samples

 Compatibility Notes


5.1 Visual Basic Samples
SocketWrench Samples

There are eight sample Visual Basic programs distributed with the SocketWrench custom control. The files will be copied to the subdirectory \samples\cswsock under your installation directory. To examine and use these programs, open the project make file from within Visual Basic.

SWECHO

This project is the sample program described in the section on Programming With SocketWrench. It establishes a connection with an echo server on a remote host and also functions as an echo server for other applications.

SWFINGER

This project implements a finger client that will return information about a user on a remote host (typically a UNIX system). Note how the control uses the Interval property to control the amount of time that the control waits for a non-blocking connection to complete.

SWFTP

This project implements a simple FTP (File Transfer Protocol) client which can be used to exchange files between systems. This sample demonstrates the basic logic that's used to connect to an FTP server, send and parse commands and establish the data connection.

SWHTTP

This project demonstrates how to connect to a Web server and retrieve an HTML document using the Hypertext Transfer Protocol (HTTP).

SWTCP

This project is a more general implementation of a client program. It allows you to specify the remote host to connect to and the port number to use. A menu option can also be set which allows the program to act as an echo server.

SWTELNET

This project implements a basic TELNET client which can be used to login to a remote host, and demonstrates the option negotiation between the client and server.

SWUDP

This project demonstrates the use of UDP datagrams to send and receive data using the echo service. The primary difference with UDP is that it's a connectionless protocol, where packets can be sent and received by any peer on the network without establishing the traditional client-server relationship.

STDIAL

This sample does not use SocketWrench, but rather demonstrates how the Remote Access Services (RAS) control can be used to establish a connection with a service provider.


Section 6.0 - Compatibility Notes
Catalyst SocketWrench 2.0
Copyright ©1995-1996, Catalyst Development Corp.

 Installing SocketWrench

 Introduction to Windows Sockets

 Programming with SocketWrench

 SocketWrench General Information

 SocketWrench Technical Information

 SocketWrench Samples

 Compatibility Notes

 CompuServe

 Microsoft

 Netcom

 NetManage

 Novell

 Trumpet

 Wollongong


6.1 CompuServe
CompuServe Compatibility Notes

Spry Internet In A Box 1.0

When a socket operation is performed that requires a SLIP/PPP connection to be established, the modem dialer will be automatically invoked by the socket library. If your application terminates while the dialer is establishing a connection, it may cause a general protection fault.


6.2 Microsoft
Microsoft Compatibility Notes

Microsoft TCP/IP 1.0a (16-Bit)

No problems are known to exist when using the control with Microsoft's TCP/IP stack. If running Windows for Workgroups, it is recommended that you upgrade to the 32-bit protocol stack available from Microsoft.

Microsoft TCP/IP 3.11a (32-Bit)

The LocalName and  LocalAddress properties may return empty strings if the local host is not specified in the hosts table. The local host name should be added to the host table in the Windows directory.

Microsoft TCP/IP 3.11b (32-Bit)

No problems are known to exist when using the control with Microsoft's 32-bit TCP/IP stack in Windows for Workgroups.

Microsoft Windows NT 3.51

A Visual Basic application using the 16-bit Windows Sockets library under Windows NT may experience problems related to socket operation timeouts. The use of blocking sockets on this platform is not recommended.


6.3 Netcom
Netcom Compatibility Notes

Netcom NetCruiser 2.1.1

The Windows Sockets library that is included with Netcom's NetCruiser product is not compatible with SocketWrench or any of the controls in the SocketTools package.


6.4 NetManage
NetManage Compatibility Notes

NetManage NEWT 3.10

If the remote host closes the connection while your application is waiting for data on a blocked socket, there may be delay until the operation returns. Although this will not adversely affect the functionality of your program, it can make it appear to be sluggish. This problem occurs because NEWT does not return immediately when the socket is closed by the peer. To work around this problem, either use non-blocking sockets or set the Timeout property to a non-zero value.


6.5 Novell
Novell Compatibility Notes

Novell LAN Workplace for DOS 4.x

Novell's implementation of the Windows Sockets library is incomplete in some areas. The use of urgent (out of band) data is not fully supported. If the host's IP address is not found in the hosts file, the library will fail an attempt to determine the host's system name.


6.6 Trumpet
Trumpet Compatibility Notes

Trumpet 2.0b

No problems are known to exist when using the control with the Trumpet.


6.7 Wollongong
Wollongong Compatibility Notes

Wollongong Pathway 2.0

Under some circumstances, the control did not work correctly with Pathway when the Blocking property was True and the Timeout property was set to zero (i.e.: block indefinately). To work around this problem, either use a non-blocking socket, or set a reasonable timeout value for the operation.